docs: add branching and comment conventions to .ai/instructions.md - #306
Merged
Conversation
Adds a Branching section to CLAUDE.md so agents branch from origin/dev and open PRs against dev instead of main. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A new worktree bases off the repo default branch (beta), not dev, so CLAUDE.md now spells out re-basing onto origin/dev before making changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Lead with the imperative (base worktrees on origin/dev) and state the beta default as a caveat, so no sentence scans as "do not use dev". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mrafnadeem-apimatic
requested review from
Shield-Jaguar,
aliasghar98 and
saeedjamshaid
as code owners
August 5, 2026 08:33
Comments must explain non-obvious why only; existing comment density in nearby code is not a reason to add more. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mrafnadeem-apimatic
changed the title
Project conventions belong in .ai/instructions.md; CLAUDE.md only points to it. Adds a Branching section (start from dev, never main, worktrees included) and a no-AI-generated-comments code convention, and reverts CLAUDE.md to its original content. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mrafnadeem-apimatic
changed the title
|
saeedjamshaid
approved these changes
Aug 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds two project conventions to
.ai/instructions.md, where this repo keeps its conventions (CLAUDE.mdonly points to that file).Branching
New
## Branchingsection, placed before## Commit Conventions:dev, nevermain— branch fromorigin/dev, open PRs againstdev.main; stop and ask if a task appears to require it.The worktree note exists because this repo's remote default branch is
beta(refs/remotes/origin/HEAD->origin/beta), notmainordev, and the three have diverged. A newly created worktree therefore starts frombeta, so the section givesgit fetch origin dev && git reset --hard origin/dev(fresh, clean worktrees only) plus a verification step.Comments
New bullet in
## Critical Code Conventions: No AI-generated comments — comment only to explain non-obvious why (a constraint, workaround, or subtle invariant); never restate the code, narrate a change, or leave notes for a future agent. Default to no comment; existing comment density nearby is never a reason to add more.CLAUDE.md
Unchanged except one word: its pointer line now reads "architecture, conventions, branching, testing, commits" so the new section is discoverable.
Notes for reviewers
devas requested and deliberately says nothing about targetingbeta. Ifbetais in practice the integration branch, this rule and the repo default disagree, and the remote default may want repointing.CLAUDE.mdbeforeec02bb9moved them here. Net diff againstdevis +11 lines in.ai/instructions.mdand 1 changed line inCLAUDE.md. Worth squashing on merge.Docs-only change; no code touched.